States

Overview

A state is a means of saving a task between game sessions so that it can be restarted later.  

Normally tasks disappear when a game session ends, such as if the game is quit, or the player transits from space into the player base, but a task with a state will be restarted when a new game session starts, as tasks with states are recorded in the save game. Tasks with states also automatically restart when the player leaves the player base and enters space.

Built into each state is a progress value. This value can be set by a script to define the progress through the state's associated task. The progress value can be used by custom Pog code to start the task at a point other than the beginning.

Additional properties can also be stored on a state using the Object functions. In this way it is possible to save a task's status more exactly, by storing properties that control how the task sets itself up. Again, specific Pog code needs to be written into the task to enable this.

When a Task with a state is no longer required its state must be destroyed to prevent it restarting again.

The State package is used to create, manipulate and destroy states.

Example

The following example code gives an example of a Pog script (in this case a mission) checking for a state and setting itself up accordingly.

// These are the enumerations for the states progress values for this script
enum eMissionState 
{ 
	MS_Start = 1,
	MS_Part_1 = 2,
	MS_Part_2 = 3
};


// First get the state handle for the current task
hstate state = State.Find( Task.Current() );
	
// Then check if the state is valid.
if ( !state )
{
	// The state isn't valid, so create one with the progress value set to the beginning.
	state = State.Create( Task.Current(), MS_Start );
}

// Now we activate different code depending on the progress value of the state
switch( State.Progress( state ) )
{
	case( MS_Start ) :	// Code for the start of the mission would go here.
				break;
	
	case( MS_Part_1 ) :	// Code for the first part of the mission would go here.
				break;

	case( MS_Part_2 ) :	// Code for the second part of the mission would go here.
				break;
}